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ABSTRACT 

The purpose of a computer program or model 
documentation is to provide the details that will aid others to use 
the program, and, more importantly, aid those who desire to modify or 
revise the program. This pamphlet presents specifications for such 
documentation, first offering a complete outline of all the 
information that should appear. Each section of 
documentation — program identification and background, user 
documentation, and programer documentation- -i s then described in 
detail. Examples are appended. (Author/SH) 
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INTRODUCTION 



The purpose of a computer program or model documentation Is to provide 
the details which will aid others to use the program but, more importantly, 
aid those who desire to modify or revise a program. Often a potential 
user cannot effectively utilize all the features of a program if he does 
not have an understanding of how the program operates. For more sophisticated 
programs, particularly those which simulate models of economic organizations 
and systems, any use at all is Impossible without a substantial and detailed 
understanding of the programme algorithm, mathematical processes and 
assumptions. In any case, a simple explanation of where on the data card 
to enter the various values is seldom sufficient.. 

For these reasons, two types of documentation are useful. The first 
is for the person who wants to use the program as it exists. The second is 
for the person who would like to modify the program in order to meet his 
specific requirements or simply to improve the program. For these reasons, 
the program documentation specifications have been divided into USER 
DOCUMENTATION and PROGRAMMER DOCUMENTATION. Carefully written programs 
should also be generously endowed with comment cards which aid in program 
modification. 

A number of programs or linear programming models have been written 
over the last several years which have not been documented. Substantial 
time, both professional and computer, has been expended to debug these 
programs and models, but after they were used for a particular project it 
was not possible for another person to use them again without virturally 
starting over. This results in a wasteful use of professional and computer 
time and incapacitates further use of the programs and models developed. 

Even if the existence of a similar program or model is knowi:., its use may 
be impaired when the documentation does not exist or is so sketchy that 
modifying the existing program requires a great deal of effort. Often a 
program or model has wide possibilities for application by others and in 
some cases this may be more useful than its application to a particular 
problem. 

The development of program and model documentation standards is 
intended to generate a class of uniform reports specifically devoted to 
program and model use and to provide a professionally recognized medium 
for displaying the work of those who expend ef'^orts in building programs 
and computer simulations. The standards of documentation worked out in 
this document are designed so that the program or model can be understood 
both by the casual as well as the sophisticated user. Examples of program 
and model documentation are given in Appendices A and B respectively. 

To achieve uniformity, an ordered listing of the material included in 
each documentation is required. This listing, called "CONTENTS OF PROGRAM 
AND MODEL DOCUMENTATION," is on the next page and should form the introduction 
and table of contents of the documentation. If a particular element in the 
documentation is not applicable, the author should state "none" after the 
element name in the body of the documentation and place "XXX" in the page 
reference space on the contents page. 
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